/**
 * @file		i2c.h
 * @brief		I2C
 * @note		None
 * @attention	None
 * 
 * <B><I>ALL RIGHTS RESERVED, COPYRIGHT&copy; SOCIONEXT INCORPORATED 2016</I></B>
 */

/** @weakgroup i2c_overview
@{
	I2C base function.<br>
	Transmission and reception of data by the I2C.<br>
	<br>
	Control parameter setting<br>
	- Communication rate : 400kbps<br>
	- Slave address length : 7 bit address<br>
	- Slave address : Specify by I2C Send buffer/I2C Receive buffer(API : iI2CSetSendBuffer() / iI2CSetReceiveBuffer())<br>
@}*//* --- end of i2c_overview */

/** @weakgroup i2c_sequence
@{
	- @ref i2c_send_sequence
	- @ref i2c_receive_sequence
	- @ref i2c_sample
	
	@section i2c_send_sequence Sequence example of I2C Transmission.
	@image html i2c_send.png
	<br>
	@section i2c_receive_sequence Sequence example of I2C Reception.
	@image html i2c_receive.png
	<br>

	<hr>
	@section i2c_sample Sample code
	The example of I2C is as follows.

	@code
	void I2C_Send_Sample()
	{
		int ret;
		T_I2C_SEND_BUFFER buff;
		
		// set Buffer.
		buff.address		= 0xXXXXXXXX;
		buff.size			= 10;
		buff.slave_address	= 0xXX;
		ret = iI2CSetSendBuffer(&buff);
		if (ret != 0) {
			return;
		}
		
		// set notification : enable.
		ret = iI2CSetSendNotification(1);
		if (ret != 0) {
			return;
		}
		
		// start.
		ret = iI2CSetSendStart();
		if (ret != 0) {
			return;
		}
	}
	void I2C_Receive_Sample()
	{
		int ret;
		T_I2C_RECEIVE_BUFFER buff;
		
		// set Buffer.
		buff.address		= 0xXXXXXXXX;
		buff.size			= 0xFF;
		buff.pointer		= 0xXXXXXXXX;
		buff.overlap		= 0;
		buff.slave_address	= 0xXX;
		ret = iI2CSetReceiveBuffer(&buff);
		if (ret != 0) {
			return;
		}
		
		// set notification : enable.
		ret = iI2CReceiveNotification(1);
		if (ret != 0) {
			return;
		}
		
		// Receive start.
		ret = iI2CReceiveStart();
		if (ret != 0) {
			iI2CReceiveStop();
			return;
		}
	}
	@endcode

@}*//* --- end of i2c_sequence */

#ifndef _I2C_H_
#define _I2C_H_

/** @weakgroup i2c_definition
@{*/

/** Send Buffer data */
typedef struct {
	unsigned long		address;		/**< start address of buffer.	*/
	unsigned long		size;			/**< byte size. 0:no-buffer.	*/
	unsigned long		slave_address;	/**< slave address.				*/
} T_I2C_SEND_BUFFER;

/** Receive Buffer data */
typedef struct {
	unsigned long		address;		/**< start address of buffer.					*/
	unsigned long		size;			/**< byte size. 0:no-buffer.					*/
	unsigned long		pointer;		/**< address of write pointer.					*/
	unsigned long		overlap;		/**< 0:no-overlap, 1:cyclic, 2:same position	*/
	unsigned long		slave_address;	/**< slave address.								*/
} T_I2C_RECEIVE_BUFFER;

/* @} */	// i2c_definition group

/** @weakgroup i2c_func
@{*/

/**
I2C Send start.
@retval  0 : success
@retval  1 : parameter error.
@retval  3 : function error.
*/
extern int iI2CSendStart(void);

/**
I2C Receive start.
@retval  0 : success
@retval  1 : parameter error.
@retval  3 : function error.
*/
extern int iI2CReceiveStart(void);

/**
I2C Receive stop.
@retval  0 : success
*/
extern int iI2CReceiveStop(void);

/**
set I2C Send notification.
@param [in]	enable		notification enable.<br>
						0:disable, 1:enable
@retval  0 : success
@retval  1 : parameter error
*/
extern int iI2CSendNotification(int enable);

/**
set I2C Receive notification.
@param [in]	enable		notification enable.<br>
						0:disable, 1:enable
@retval  0 : success
@retval  1 : parameter error
*/
extern int iI2CReceiveNotification(int enable);

/**
set I2C input buffer for send.
@param [in]	buff		Send buffer data.
@retval  0 : success
@retval  1 : parameter error
*/
extern int iI2CSetSendBuffer(T_I2C_SEND_BUFFER const* const buff);

/**
set I2C input buffer for receive.
@param [in]	buff		Receive buffer data.
@retval  0 : success
@retval  1 : parameter error
*/
extern int iI2CSetReceiveBuffer(T_I2C_RECEIVE_BUFFER const* const buff);

/* @} */	// i2c_func group

#endif	// _I2C_H_
